<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="module-smtpd.html" />
<link rel="prev" href="module-nntplib.html" />
<link rel="parent" href="internet.html" />
<link rel="next" href="SMTP-objects.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>18.13 smtplib -- SMTP protocol client</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="18.12.1 nntp Objects"
  href="nntp-objects.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="18. internet Protocols and"
  href="internet.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="18.13.1 smtp Objects"
  href="SMTP-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="nntp-objects.html">18.12.1 NNTP Objects</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="internet.html">18. Internet Protocols and</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="SMTP-objects.html">18.13.1 SMTP Objects</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h1><a name="SECTION00201300000000000000000">
18.13 <tt class="module">smtplib</tt> --
         SMTP protocol client</a>
</h1>

<p>
<a name="module-smtplib"></a>

<p>
<a id='l2h-4199' xml:id='l2h-4199'></a><a id='l2h-4209' xml:id='l2h-4209'></a>

<p>
The <tt class="module">smtplib</tt> module defines an SMTP client session object that
can be used to send mail to any Internet machine with an SMTP or ESMTP
listener daemon.  For details of SMTP and ESMTP operation, consult
<a class="rfc" id='rfcref-103155' xml:id='rfcref-103155'
href="http://www.faqs.org/rfcs/rfc821.html">RFC 821</a> (<em class="citetitle"
 >Simple Mail Transfer Protocol</em>) and <a class="rfc" id='rfcref-103157' xml:id='rfcref-103157'
href="http://www.faqs.org/rfcs/rfc1869.html">RFC 1869</a>
(<em class="citetitle"
 >SMTP Service Extensions</em>).

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-4200' xml:id='l2h-4200' class="class">SMTP</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>host</var><big>[</big><var>, port</var><big>[</big><var>,
                        local_hostname</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
A <tt class="class">SMTP</tt> instance encapsulates an SMTP connection.  It has
methods that support a full repertoire of SMTP and ESMTP
operations. If the optional host and port parameters are given, the
SMTP <tt class="method">connect()</tt> method is called with those parameters during
initialization.  An <tt class="exception">SMTPConnectError</tt> is raised if the
specified host doesn't respond correctly.

<p>
For normal use, you should only require the initialization/connect,
<tt class="method">sendmail()</tt>, and <tt class="method">quit()</tt> methods.  An example is
included below.
</dl>

<p>
A nice selection of exceptions is defined as well:

<p>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-4201' xml:id='l2h-4201' class="exception">SMTPException</tt></b></dt>
<dd>
  Base exception class for all exceptions raised by this module.
</dd></dl>

<p>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-4202' xml:id='l2h-4202' class="exception">SMTPServerDisconnected</tt></b></dt>
<dd>
  This exception is raised when the server unexpectedly disconnects,
  or when an attempt is made to use the <tt class="class">SMTP</tt> instance before
  connecting it to a server.
</dd></dl>

<p>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-4203' xml:id='l2h-4203' class="exception">SMTPResponseException</tt></b></dt>
<dd>
  Base class for all exceptions that include an SMTP error code.
  These exceptions are generated in some instances when the SMTP
  server returns an error code.  The error code is stored in the
  <tt class="member">smtp_code</tt> attribute of the error, and the
  <tt class="member">smtp_error</tt> attribute is set to the error message.
</dd></dl>

<p>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-4204' xml:id='l2h-4204' class="exception">SMTPSenderRefused</tt></b></dt>
<dd>
  Sender address refused.  In addition to the attributes set by on all
  <tt class="exception">SMTPResponseException</tt> exceptions, this sets `sender' to
  the string that the SMTP server refused.
</dd></dl>

<p>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-4205' xml:id='l2h-4205' class="exception">SMTPRecipientsRefused</tt></b></dt>
<dd>
  All recipient addresses refused.  The errors for each recipient are
  accessible through the attribute <tt class="member">recipients</tt>, which is a
  dictionary of exactly the same sort as <tt class="method">SMTP.sendmail()</tt>
  returns.
</dd></dl>

<p>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-4206' xml:id='l2h-4206' class="exception">SMTPDataError</tt></b></dt>
<dd>
  The SMTP server refused to accept the message data.
</dd></dl>

<p>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-4207' xml:id='l2h-4207' class="exception">SMTPConnectError</tt></b></dt>
<dd>
  Error occurred during establishment of a connection  with the server.
</dd></dl>

<p>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-4208' xml:id='l2h-4208' class="exception">SMTPHeloError</tt></b></dt>
<dd>
  The server refused our "<tt class="samp">HELO</tt>" message.
</dd></dl>

<p>
<div class="seealso">
  <p class="heading">See Also:</p>

  <dl compact="compact" class="seerfc">
    <dt><a href="http://www.faqs.org/rfcs/rfc821.html"
        title="Simple mail Transfer Protocol"
        >RFC 821, <em>Simple Mail Transfer Protocol</em></a>
    <dd>Protocol definition for
          SMTP.  This document covers the model, operating procedure,
          and protocol details for SMTP.
  </dl>
  <dl compact="compact" class="seerfc">
    <dt><a href="http://www.faqs.org/rfcs/rfc1869.html"
        title="SMTP service Extensions"
        >RFC 1869, <em>SMTP Service Extensions</em></a>
    <dd>Definition of the ESMTP
          extensions for SMTP.  This describes a framework for
          extending SMTP with new commands, supporting dynamic
          discovery of the commands provided by the server, and
          defines a few additional commands.
  </dl>
</div>

<p>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<a name="CHILD_LINKS"><strong>Subsections</strong></a>

<ul class="ChildLinks">
<li><a href="SMTP-objects.html">18.13.1 SMTP Objects</a>
<li><a href="SMTP-example.html">18.13.2 SMTP Example</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="18.12.1 nntp Objects"
  href="nntp-objects.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="18. internet Protocols and"
  href="internet.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="18.13.1 smtp Objects"
  href="SMTP-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="nntp-objects.html">18.12.1 NNTP Objects</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="internet.html">18. Internet Protocols and</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="SMTP-objects.html">18.13.1 SMTP Objects</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
